home *** CD-ROM | disk | FTP | other *** search
- FTNCHOP(1) Last changed: 7-23-97
-
-
- NNAAMMEE
- ffttnncchhoopp - Invokes the program unit problem isolator
-
- SSYYNNOOPPSSIISS
- ffttnncchhoopp [--GG] [--BB] [--gg _g_d_i_r] [--bb _d_i_r] [--rr] [--vv] [--VV] LLIISSTT
-
- IIMMPPLLEEMMEENNTTAATTIIOONN
- UNICOS, UNICOS/mk, and IRIX systems
-
- DDEESSCCRRIIPPTTIIOONN
- The ffttnncchhoopp utility is a program that isolates problems to object file
- level by using a mix-and-match technique. This utility is most useful
- with programs that contain several source files. To run the ffttnncchhoopp
- utility you need to have one working version of a program and one
- version that is not working. When run, ffttnncchhoopp finds the object files
- that are causing the program to malfunction. Debugging efforts can
- then be concentrated to those files.
-
- The ffttnncchhoopp utility works by selecting object files from two
- directories _g_d_i_r and _b_d_i_r, whose default names are GGOOOODD and BBAADD. It
- reads the list of object files from file LLIISSTT, one file name per line
- with no trailing blanks. To make a trial run, ffttnncchhoopp prefixes object
- file names with _g_d_i_r// or _b_d_i_r// and writes them to a file named
- FFTTNNCCHHOOPP__LLIISSTT. It then executes the program or shell script named
- FFTTNNCCHHOOPP__TTEESSTT. This program or shell script links the program by using
- the list in FFTTNNCCHHOOPP__LLIISSTT, tests it, and returns an exit status of zero
- if the test passed and a non-zero exit status if the test failed.
- Depending on the return value, ffttnncchhoopp will change the list and call
- FFTTNNCCHHOOPP__TTEESSTT again until it has found one file in _b_d_i_r that is causing
- the failure. At this point ffttnncchhoopp will run another test to determine
- if that was the only bad file. If not, ffttnncchhoopp will repeat the test
- process with the remaining files until all bad files are found.
-
- Before doing any mixing, ffttnncchhoopp checks the boundary conditions by
- making one run with all good files and another run with all bad files.
- These checks can be skipped if you specify the --GG and --BB options,
- respectively. If these checks are skipped and the boundary conditions
- are not correct, that is if the program with all good files fails or
- if the program with all bad files passes, ffttnncchhoopp can return
- inaccurate information.
-
- The ffttnncchhoopp command accepts the following options:
-
- --GG Specifies that ffttnncchhoopp skip checking boundry
- conditions on good files.
-
- --BB Specifies that ffttnncchhoopp skip checking boundry
- conditions on bad files.
-
- --gg _g_d_i_r Specifies name of directory containing the good
- files. Default is GGOOOODD.
-
- --bb _g_d_i_r Specifies name of directory containing the bad files.
- Default is BBAADD.
-
- --rr Restarts ffttnncchhoopp from the point where the test run
- was aborted. Must be the only option on the command
- line.
-
- --vv Specifies that the entire contents of FFTTNNCCHHOOPP__LLIISSTT is
- printed. Default is to print a single line that
- lists the name of the bad file.
-
- --VV Displays version, date, and time of the ffttnncchhoopp
- executable running on your system. If this is the
- only option specified on the command line, the
- utility exits after printing the information; the
- tool itself is not started.
-
- NNOOTTEESS
- Depending on the number of files and the length of the test run,
- ffttnncchhoopp can take several hours to complete.
-
- All object files and test files must remain unmodified during the
- entire run. The test script must be written carefully so that it does
- not depend on any previous run in any way.
-
- By default ffttnncchhoopp prints just one message line for each bad file
- found:
-
- ##### FOUND BAD FILE _f_i_l_e
-
- It is advisable to print the contents of FFTTNNCCHHOOPP__LLIISSTT to keep a record
- of the entire run.
-
- The ffttnncchhoopp utility makes no distinction between a test failure and a
- script failure. If the script FFTTNNCCHHOOPP__TTEESSTT has a syntax error, or if
- the ff9900 comand fails for any reason, ffttnncchhoopp assumes a test failure.
-
- If the --GG switch is not specified, the utility stops as soon as it
- finds the all-good file test failing. Otherwise it will find all the
- files to be bad and return inaccurate information. Therefore, it is
- advisable to watch the starting of a ffttnncchhoopp run to make sure it is
- progressing correctly.
-
- While ffttnncchhoopp is running a test, it writes state information to a file
- called FFTTNNCCHHOOPP__SSTTAATT. If a run aborts for any reason, you can restart
- ffttnncchhoopp from that point by entering the following command:
-
- ftnchop -r
-
- This causes ffttnncchhoopp to read state information from FFTTNNCCHHOOPP__SSTTAATT. This
- state information includes the names of the good and bad directories
- and all the options.
-
- ffttnncchhoopp does not require that files be object files.
-
- EEXXAAMMPPLLEESS
- A typical situation occurs when a large program made of several object
- files works when compiled without optimization but not when compiled
- with optimization. To use ffttnncchhoopp to locate the problem, create two
- directories, for example OO00 and OO22. Keep all unoptimized object files
- in directory OO00 and optimized files in directory OO22. Then create an
- automated method of determining the success of a program test run.
- One way would be to create a shell script named FFTTNNCCHHOOPP__TTEESSTT that
- causes the program to print TTEESSTT PPAASSSSEEDD at the end of a successful run
- but return a message of TTEESSTT FFAAIILLEEDD upon an unsuccessful run. The
- shell script would look like the following script:
-
- echo ================= TESTING WITH: ==================
- cat FTNCHOP_LIST
- f77 -o prog `cat FTNCHOP_LIST`
- prog > RESULT
- tail -l RESULT > t1
- if grep t1 'RUN COMPLETED'
- then
- echo TEST PASSED
- exit 0
- else
- echo TEST FAILED
- exit 1
- fi
- Make sure the script has executable permission. Make a file
- containing the names of all constituent files, one per line, by using
- the following format:
-
- /bin/ls O0 > OLIST
-
- The execute the ffttnncchhoopp command as follows:
-
- ftnchop -gO0 -bO2 OLIST > FTNCHOP.RES
- After the run is complete, enter the following ggrreepp command to find
- the bad files:
-
- grep FOUND FTNCHOP.RES
-
- Another example of failure can occur when a program gets an exception
- error and dumps core memory. In this case the test that a failure
- occurred may be the existence of a core file, as shown in the
- following example:
-
- rm -f core # _r_e_m_o_v_e _f_r_o_m _a_n_y _p_r_e_v_i_o_u_s _r_u_n_s
- prog > RESULT
- if test -f core
- then
- exit 1
- else
- exit 0
- fi
-
- FFIILLEESS
- BBAADD Default name of the directory containing the
- "bad" files.
-
- GGOOOODD Default name of the directory containing the
- "good" files.
-
- FFTTNNCCHHOOPP__LLIISSTT List of files to be tested by ffttnncchhoopp.
-
- FFTTNNCCHHOOPP__TTEESSTT Name of test script called by ffttnncchhoopp.
-
- SSEEEE AALLSSOO
- ff9900(1) and ffttnnsspplliitt(1)
-
- This man page is available only online.
-